Go 整合 Swagger

这个 Swagger 是啥就不多说，Java 时写吐了都要，不过在 Golang 中看到这熟悉的面孔还是挺惊喜的。

配置环境

首先安装 swag

# 下载安装swag
go get -u github.com/swaggo/swag/cmd/swag

若 $GOROOT/bin 没有加入 $PATH 中，你需要执行将其可执行文件移动到 $GOBIN 下

mv $GOPATH/bin/swag $GOROOT/bin

验证是否安装成功

$ swag -v
swag version v1.7.4

安装 gin-swagger

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

编写 API 注释

Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

gin-swagger 给出的范例：

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
    g.JSON(http.StatusOK,"helloworld")
}

参照 Swagger 的注解规范和范例去编写

// @Summary 新增文章标签
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {

// @Summary 修改文章标签
// @Produce  json
// @Param id path int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {

在完成了注解的编写后，我们需要针对 swagger 新增初始化动作和对应的路由规则，才可以使用。打开 routers/router.go 文件，新增内容如下：

package routers

import (
    ...

    _ "std01/docs" // 注意，这里要引入项目的 docs 目录，否则会报错

    ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"

    ...
)

// InitRouter initialize routing information
func InitRouter() *gin.Engine {
    ...
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    ...

    return r
}

进入到 gin-blog 的项目根目录中，执行初始化命令

swag init

就生成了如下文件

启动当前项目后，然后访问

http://172.29.41.24:9999/swagger/index.html

配置环境​

编写 API 注释​

配置环境

编写 API 注释